%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%   BornAgain User Manual
%%
%%   homepage:   http://www.bornagainproject.org
%%
%%   copyright:  Forschungszentrum Jülich GmbH 2015
%%
%%   license:    Creative Commons CC-BY-SA
%%
%%   authors:    Scientific Computing Group at MLZ Garching
%%               C. Durniak, M. Ganeva, G. Pospelov, W. Van Herck, J. Wuttke
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\def\ffsection#1{%
\FloatBarrier\clearpage
\section{#1}}

\def\ffref#1{\texttt{#1} (\cref{S#1})}

% Don't number subfigures in this chapter.
\makeatletter
\renewcommand{\@thesubfigure}{\relax}
\makeatother

\index{Cone|see{Frustum}}
\index{Cuboid|see{Box}}
\index{Expansion|see{Cantellation}}
\index{Prism!reactangular|see{Box}}
\index{Tilt|see{Rotation}}
\index{Truncation|seealso{Facetting}}
\index{Truncation!cone|see{Frustum}}
\index{Truncation!pyramid|see{Frustum}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}\label{SPFF}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

BornAgain comes with a comprehensive collection of hard-coded shape transforms
\index{Shape transform}%
for standard particle geometries like
spheres, cylinders, prisms, pyramids or ripples.
This collection is documented in the following.
For each shape,
the real-space geometry is shown in orthogonal projections,
the parameters of the BornAgain method are defined,
an analytical expression for the form factor is given,
and exemplary results for $\left|F(\q)\right|^2$ versus
$\alpha_\sf,\phi_\sf$ are shown for small-angle scattering conditions
($\alpha_\si=\phi_\si=0$).

The computation of $F(\q)$ is based on
shapes $S(\r)$ given in Cartesian coordinates,
as defined in the orthogonal projections.
Typically, the vertical ($z$) direction is chosen
along a symmetry axis of the particle.
The origin is always at the center of the bottom side of the particle.
Different parametrization or a different choice of the origin
cause our analytic form factors to trivially deviate
from expressions given in the \IsGISAXS\ manual \cite[Sec.~2.3]{Laz06}
or in the literature \cite[Appendix]{ReLL09}.

We made sure that all expressions also hold for complex scattering vectors ~$\q$,
\index{q@$q$ (scattering vector)}%
\index{Scattering vector}%
used to describe in order to take any material absorption into account.
\index{Absorption}%
In standard reflectometry geometry, with reference surface normal to $\v{\hat z}$,
\index{z@$z$ (surface normal coordinate)}%
\index{Coordinates}%
\index{Surface}%
only the vertical components of $\k_\si$ and $\k_\sf$ can have imaginary parts.
However,
for tilted particles
$F(\v{\tilde{q}})$ needs to be computed with
a rotated scattering vector~$\v{\tilde q}$
that may be complex in all three components.
Therefore BornAgain allows all three components of~$\q$ to be complex.

In the following,
information about the implemented geometries is given in standardized form.
Analytical expressions are given for the form factor $F(\q)$,
for the volume $V=F(0)$,
\index{Volume}%
and for the maximum horizontal section $S$
(the area of the particle as seen from above).
Mathematical notation in the form factor expressions includes
the cardinal sine functions $\sinc(z)\coloneqq\sin(z)/z$
\index{sinc (sinus cardinalis)}%
and the Bessel function of first kind and first order $J_1(z)$
\index{J@$J_1$ (Bessel function)}%
\index{Bessel function}%
\cite[Ch.~9]{AbSt64}.
If results contain an integral,
then no analytical form was found,
and the integral is evaluated by numeric quadrature.
\index{Quadrature}%
For polyhedral figures,
\index{Polyhedron!generic algorithm}%
except a few simple ones like the rectangular box,
we use a generic form factor computation,
parametrized by the vertices of the figure,
that is described in full detail in a mathematical paper~\cite{Wut17}.

Almost all analytical expressions for $F(\q)$ contain
removable singularities for certain values of $\q$.
Our implementation uses proper analytic continuations at these singularities,
\index{Singularity!in form factor computation}%
though this is not explicitly denoted in the following formula collection.
Furthermore, series expansions are used to ensure numeric accuracies
in the neighborhood of the singularities.
For polyhedra, see Ref.~\cite{Wut17} for a meticulous discussion.

\begin{figure}[t]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_demo_1quadrants.pdf}
\end{center}
\caption{Normalized intensity $I(\alpha_\sf,\phi_\sf)$
for small-angle scattering by a truncated sphere with $R=4.2$~nm and $H=6.1$~nm,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).
Since $I$ possess the standard symmetry (\protect\ref{EFq4sym}),
data are only shown for first quadrant $0^\circ\le\phi_\sf,\alpha_\sf\le 5^\circ$.}
\label{F1quadrants}
\end{figure}

Geometrical objects can be parametrized in different ways.
Concerns about user experience and about code readability
sometimes lead to different choices.
For the BornAgain user interfaces (GUI and API)
we have chosen the most standard parameters,
as used in elementary geometry, like length, height, radius,
even if this is at variance from the \IsGISAXS\ precedent.
Where our parametrization made analytic expressions too tedious,
we use alternate internal parameters to alleviate the formul\ae.

Examplary form factors are numerically computed in Born approximation.
All simulations scripts can be found in the BornAgain sources in directory
\href{https://github.com/scgmlz/BornAgain/tree/master/Doc/FFCatalog/fig/ff2}%
{Doc/FFCatalog/fig/ff2}.
The particles are assigned a refractive index of $n=10^{-5}$.
\index{Refractive index}%
Parameters are chosen such that
the particle volume~$V$
\index{Volume}%
is about 250~nm$^3$ (within $\pm5$~\%);
except ripples, which are chosen with a vertical section $V/L$ of 40~nm$^2$
and a length of 25~nm.
The incident wavelength is 1~\AA.
The incident beam is always in $x$ direction, hence $\alpha_\si=\phi_\si=0$.
Simulated detector images are normalized to the maximum scattering intensity at $F(0)=V$,
\begin{equation}
  I(\alpha_\sf,\phi_\sf)\coloneqq |F(q(\alpha_\sf,\phi_\sf))|^2/V^2.
\end{equation}
All plots
\index{Plotting}%
have the same logarithmic color scale,
extending over eight decades from $10^{-8}$ to~1.
Plot ranges in $\alpha_\sf$ and $\phi_\sf$ are also standardized as far as
reasonably possible.
For some geometries,
the simulated detector image has some symmetry,
\index{Symmetry}
namely horizontal or/and vertical mirror planes:
\index{Mirror planes}
\begin{equation}\label{EFq4sym}
  I(\alpha_\sf,\phi_\sf)
  = I(\alpha_\sf,-\phi_\sf)
  = I(-\alpha_\sf,-\phi_\sf)
  = I(\alpha_\sf,-\phi_\sf).
\end{equation}
% TODO RESTORE TEMPORARILY REMOVED XREF
% The physical origin this symmetry is discussed in \cref{Ssym}.
In these cases, we tend to restrict
plots of $I$ to the quadrant $\alpha_\sf\ge0$, $\phi_\sf\ge0$.
However, it requires some experience to fully appreciate the
information content of these plots.
For a demonstration of this,
try to grasp the main features of \cref{F1quadrants}.
Then compare with \cref{F4quadrants}.

\begin{figure}[t]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_demo_4quadrants.pdf}
\end{center}
\caption{Same data as in Fig.~\protect\ref{F1quadrants},
but now shown for all four quadrants ($-5^\circ\le\phi_\sf,\alpha_\sf\le 5^\circ$).
The vertical interference pattern,
which gradually disappears with increasing tilt angle,
 is much more salient in this plot
than in the preceding one-quadrant representation.}
\label{F4quadrants}
\end{figure}

\index{Large particles!numeric difficulty}%
\index{Numeric difficulty!form factor oscillation}%
\index{Oscillation!from large particle form factor}%
\index{Monte-Carlo integration!for large particle form factor}%
\index{Particle!rapid form factor oscillation}%
Finally, one warning: For large particles (typically of order 1000~nm),
  the form factor oscillates rapidly within one detector bin
  so that analytical calculations (performed for the bin center)
  may give a completely wrong intensity pattern.
Several ways to work around this problem are proposed in Sect.~5.3
of our reference paper~\cite{PoHB20}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Hard particles}\label{SHPFF}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{Particle!hard|(}

The following tables summarize the implemented particle geometries,
 roughly ordered by decreasing symmetry.
Afterwards, the detailed documentation is in alphabetical order.

%\clearpage\thispagestyle{empty}
\def\figuredentry#1#2#3#4#5#6{%
 #2 &
 \texttt{#1}& %\newline\textsl{#1} &
#5 & % symmetry
#4 & % parameters
Page~\pageref{S#3}\\} % , \cref{S#3}
\def\sizedentry#1#2#3#4#5{\figuredentry{#1}{\hspace{#5ex}\raisebox{#4ex}{\includefinal{#3em}{fig/blue/#2.png}}}}
\def\entry#1#2{\sizedentry{#1}{#2}{5}{-3.8}{0}}
\begin{center}
  \def\h{\text{h}}
  \def\v{\text{v}}
\small
\begin{longtable}
  {@{}p{.14\textwidth}
   @{}p{.32\textwidth}
   @{}p{.17\textwidth}
   @{}p{.19\textwidth}
   @{}p{.15\textwidth}@{}}
% Shape&{Name\newline \textsl{Legacy Name}}&Symmetry&Parameters&Reference\\\hline
Shape&Name&Symmetry&Parameters&Reference\\\hline\\[-2ex]
\sizedentry{Dot}{Dot3d}{2}{-2}{2}{Dot}{$R_\text{scat}$}{R$_3$}{Dot}
\entry{FullSphere}{FullSphere3d}{FullSphere}{$R$}{R$_3$}{Sphere}
\entry{FullSpheroid}{FullSpheroid3d}{FullSpheroid}{$R$, $H$}{D$_{\infty\h}$}{Spheroid}
\entry{Cylinder}{Cylinder3d}{Cylinder}{$R$, $H$}{D$_{\infty\h}$}{Cylinder}
\entry{TruncatedSphere}{Sphere3d}{TruncatedSphere}{$R$, $H$}{C$_{\infty\v}$}{SphericalCap}
\entry{TruncatedSpheroid}{Spheroid3d}{TruncatedSpheroid}{$R$, $H$, $f_p$}{C$_{\infty\v}$}{SpheroidalCap}
\entry{Cone}{Cone3d}{Cone}{$R$, $H$, $\alpha$}{C$_{\infty\v}$}{ConicalFrustum}
\entry{Icosahedron}{Icosahedron3d}{Icosahedron}{$L$}{I$_\h$}{Icosahedron}
\entry{Dodecahedron}{Dodecahedron3d}{Dodecahedron}{$L$}{I$_\h$}{Dodecahedron}
\entry{TruncatedCube}{TruncatedCube}{TruncatedCube}{$L$, $t$}{O$_\h$}{TruncatedCube}
\sizedentry{CantellatedCube}{Box3d}{0.1}{0}{0}%TODO
{CantellatedCube}{$L$, $t$}{O$_\h$}{CantellatedCube}
\entry{Prism6}{Prism63d}{Prism6}{$R$, $H$}{D$_{6\h}$}{Prism6}
\entry{Cone6}{Cone63d}{Cone6}{$R$, $H$, $\alpha$}{C$_{6\v}$}{Frustum6}
\entry{Pyramid}{Pyramid3d}{Pyramid}{$L$, $H$, $\alpha$}{C$_{4\v}$}{Frustum4}
\entry{Cuboctahedron}{Cuboctahedron3d}{Cuboctahedron}{$L$, $H$, $r_H$, $\alpha$}{C$_{4\v}$}{BiFrustum4}
\entry{Prism3}{Prism33d}{Prism3}{$L$, $H$}{D$_{3\h}$}{Prism3}
\entry{Tetrahedron}{Tetrahedron3d}{Tetrahedron}{$L$, $H$, $\alpha$}{C$_{3\v}$}{Frustum3}
\entry{EllipsoidalCylinder}{EllipsoidalCylinder3d}{EllipsoidalCylinder}{$R_a$, $R_b$, $H$}{D$_{2\h}$}{EllipsoidalCylinder}
\entry{Box}{Box3d}{Box}{$L$, $W$, $H$}{D$_{2\h}$}{Prism2}
\entry{HemiEllipsoid}{HemiEllipsoid3d}{HemiEllipsoid}{$R_a$, $R_b$, $H$}{C$_{2\v}$}{HemiEllipsoid}
\entry{AnisoPyramid}{AnistropicPyramid3d}{AnisoPyramid}{$L$, $W$, $H$, $\alpha$}{C$_{2\v}$}{Frustum2}
\hline
\end{longtable}
\end{center}
%\thispagestyle{empty}\clearpage

\index{Rotation of particles}
\index{Orientation of particles}
\index{CreateRotateX@\Code{CreateRotateX}}
\index{Transform3D@\Code{Transform3D}}

%===============================================================================
\ffsection{AnisoPyramid (rectangle-based)} \label{SAnisoPyramid}
%===============================================================================
\index{Frustum!reactangular base}
\index{Anisotropic pyramid}
\index{Pyramid!rectangular}
\index{FormFactorAnisoPyramid@\Code{FormFactorAnisoPyramid}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/AnistropicPyramid3d.png}}
\hfill
\subfigure[Top view]{\includegraphics[width=.30\textwidth]{fig/cuts/AnisoPyramid2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{2mm}{\includegraphics[width=.30\textwidth]{fig/cuts/AnisoPyramid2dxz.pdf}}}
\hfill
\caption{A truncated pyramid with a rectangular base.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorAnisoPyramid(double length, double width, double height, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the base, $L$,
\item \texttt{width} of the base, $W$,
\item \texttt{height}, $H$
\item \texttt{alpha}, angle between the base and a side face, $\alpha$.
\end{itemize}
They must fulfill
\begin{displaymath}
  H \le \frac{\tan\alpha}{2} \min\,(L,W).
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic polyhedron form factor~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V= H \Big[LW - \dfrac{(L + W)H}{\tan\alpha} + \dfrac{4}{3} \dfrac{H^2}{\tan^2\alpha}\Big].
\end{equation*}
\begin{equation*}
  S=LW.
\end{equation*}

\paragraph{Examples}\strut\\
\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_AnisoPyramid.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=13$~nm, $W=8$~nm, $H=4.2$~nm, and $\alpha=60^\circ$,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\label{fig:FFAnisoPyramidEx}
\end{figure}

\paragraph{History}\strut\\
Agrees with the \E{In-plane anisotropic pyramid} form factor of \IsGISAXS\
\cite[Eq.~2.40]{Laz06} \cite[Eq.~217]{ReLL09},
except for different parametrization.
This is \E{not} the \E{anisotropic pyramid} of \FitGISAXS,
which is a true pyramid with an off-center apex \cite{Bab13}.

Formfactors~$F(\q)$ have been checked against the different computation of \IsGISAXS,
and were found to fully agree.

\paragraph{See also}
\begin{itemize}
\item \ffref{Box} if $\alpha=0$,
\item \ffref{Pyramid} if $L=W$.
\end{itemize}

%===============================================================================
\ffsection{Box (cuboid)} \label{SBox}
%===============================================================================
\index{Box}
\index{Cube}
\index{Platonic solid!cube}
\index{FormFactorBox@\Code{FormFactorBox}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Box3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Box2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Box2dxz.pdf}}}
\hfill
\caption{A rectangular cuboid.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorBox(double length, double width, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the base, $L$,
\item \texttt{width} of the base, $W$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}

\begin{equation*}
F= L W H\exp\left(i q_z \frac{H}{2}\right) \sinc\left(q_x \frac{L}{2}\right)
\sinc\left(q_y \frac{W}{2}\right) \sinc\left(q_z \frac{H}{2}\right),
\end{equation*}
\begin{equation*}
  V= LWH,
\end{equation*}
\begin{equation*}
  S = LW.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Box.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=18$~nm, $W=4.6$~nm, and $H=3$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Agrees with \E{Box} form factor of \IsGISAXS\
\cite[Eq.~2.38]{Laz06} \cite[Eq.~214]{ReLL09},
except for factors $1/2$ in the definitions of parameters $L$, $W$, $H$.

\paragraph{See also}
\begin{itemize}
\item \ffref{AnisoPyramid} or \ffref{Pyramid}
  if sides are not vertical,
\item \ffref{TruncatedCube} if $L=W=H$ and corners are facetted,
\item \ffref{CantellatedCube} if $L=W=H$ and corners and edges are facetted,
\item Sect.~\ref{SBar} if elongated in one horizontal direction.
\end{itemize}

%===============================================================================
\ffsection{CantellatedCube} \label{SCantellatedCube}
%===============================================================================
\index{Cube!cantellated}
\index{Octahedron!cantellated}
\index{Cantellation!cube}
\index{FormFactorCantellatedCube@\Code{FormFactorCantellatedCube}}

\paragraph{Real-space geometry}\strut\\

% \begin{figure}[H]
% \hfill
% \subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/CantellatedCube3d.png}}
% \hfill
% \subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Facettedcube2_2dxy.pdf}}
% \hfill
% \subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Facettedcube2_2dxz.pdf}}
% \hfill
% \caption{A cube whose eight vertices have been removed.
% The truncated part of each vertex is a trirectangular tetrahedron.}
% \end{figure}

A cube with truncated edges and vertices as in Fig~7 of Croset 2017 \cite{Cro17}.
Can also be obtained by cantellating an octahedron.
\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorCantellatedCube(double length, double removed_length)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the full cube, $L$,
\item \texttt{removed\_length}, side length of the trirectangular tetrahedron removed from the cube's vertices, $t$.
\end{itemize}
They must fulfill
\begin{displaymath}
  t \le L/2.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: use the generic form factor of a polyhedron
             with inversion symmetry~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V = L^3 - 6 L t^2 + \frac{16}{3} t^3.
\end{equation*}
\begin{equation*}
  S = L^2.
\end{equation*}

\paragraph{Examples}\strut

% \begin{figure}[H]
% \begin{center}
% \includefinal{1\TW}{fig/ff2/ff_CantellatedCube.pdf}
% \end{center}
% \caption{Normalized intensity $|F|^2/V^2$,
% computed with $L=25$~nm, $W=10$~nm, $H=8$~nm, and $d=5$~nm,
% for four different angles~$\omega$ of rotation around the $z$ axis.}
% \end{figure}

\paragraph{History}\strut\\
Introduced in BornAgain--1.17 (Python only).
Motivated by Croset 2017 \cite{Cro17}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Box} if $t=0$,
\item \ffref{TruncatedCube} if only the vertices are facetted.
\end{itemize}


%===============================================================================
\ffsection{Cone (circular)} \label{SCone}
%===============================================================================
\index{Frustum!circular base}
\index{FormFactorCone@\Code{FormFactorCone}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Cone3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Cone2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{3mm}{\includefinal{.3\TW}{fig/cuts/Cone2dxz.pdf}}}
\hfill
\caption{A truncated cone with circular base.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorCone(double radius, double height, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius}, $R$,
\item \texttt{height}, $H$,
\item \texttt{alpha}, angle between the side and the base, $\alpha$.
\end{itemize}
They must fulfill
\begin{displaymath}
  H\le R\tan\alpha.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  R_H \coloneqq R-\dfrac{H}{\tan \alpha}, \quad
  q_{\parallel} \coloneqq \sqrt{q_x^2+ q_y^2}, \quad
  \tilde{q}_z \coloneqq q_z \tan\alpha.
\end{equation*}
Results:
\begin{equation*}
  F = 2\pi \tan\alpha\; \e^{i\tilde{q}_z R}
      \int_{R_H}^R \!\d\rho\, \rho^2
        \frac{J_1(q_{\parallel}\rho)}{q_{\parallel}\rho}\,\e^{-i\tilde{q}_z \rho},
\end{equation*}
\begin{equation*}
  V = \dfrac{\pi}{3}\tan\alpha  \left( R^3 - R_H^3\right),
\end{equation*}
\begin{equation*}
  S=\pi R^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Cone.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=4$~nm, $H=11$~nm, and $\alpha=75^\circ$,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).}
\end{figure}

\paragraph{History and Derivation}\strut\\
Agrees with \E{Cone} form factor of \IsGISAXS\
\cite[Eq.~2.28]{Laz06} \cite[Eq.~225]{ReLL09},
except for a substitution $z\to\rho$ in our expression for~$F$.
Justification for complex~$q$ in the same way as for the \E{Cylinder} form factor
in \cref{SCylinder}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Cylinder} if $\alpha=0$.
\end{itemize}


%===============================================================================
\ffsection{Cone6 (hexagonal)} \label{SCone6}
%===============================================================================
\index{Frustum!hexagonal base}
\index{Pyramid!hexagonal}
\index{FormFactorCone6@\Code{FormFactorCone6}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Cone63d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Cone62dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{5mm}{\includefinal{.3\TW}{fig/cuts/Cone62dxz.pdf}}}
\hfill
\caption{A truncated pyramid, based on a regular hexagon}
\end{figure}

\FloatBarrier
\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorCone6(double base_edge, double height, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{base\_edge}, edge of the regular hexagonal base, $R$,
\item \texttt{height}, $H$,
\item \texttt{alpha}, dihedral angle between the base and a side face, $\alpha$.
\end{itemize}
Note that the orthographic projection does not show~$\alpha$,
but the angle~$\beta$ between the base and a side edge.
They are related through $\sqrt{3}\tan \alpha = 2 \tan \beta$.
The following is written more conveniently in terms of~$\beta$.
The parameters must fulfill
\begin{displaymath}
  H \le (\tan\beta)R.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic polyhedron form factor~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V = \tan\beta  \left( R^3- \left(R-\frac{H}{\tan\beta}\right)^3 \right),
\end{equation*}
\begin{equation*}
  S =\dfrac{3\sqrt{3}R^2}{2}.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Cone6.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=6$~nm, $H=5$~nm, and $\alpha=60^\circ$,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Our parametrization deviates from the form factor \E{Cone6} of \IsGISAXS
\cite[Eq.~2.32]{Laz06} \cite[Eq.~222]{ReLL09}.

Up to \BornAgain-1.5 computed by numeric integration, as in \IsGISAXS.
Since \BornAgain-1.6 higher speed and better accuracy are achieved
by using the generic polyhedron form factor \cite{Wut17},
with series expansions near singularities.

\paragraph{See also}
\begin{itemize}
\item \ffref{Prism6} if $\alpha=0$.
\end{itemize}


%===============================================================================
\ffsection{Cuboctahedron} \label{SCuboctahedron}
%===============================================================================
\index{Cuboctahedron}
\index{Platonic solid!octahedron}
\index{FormFactorCuboctahedron@\Code{FormFactorCuboctahedron}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Cuboctahedron3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Cuboctahedron2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Cuboctahedron2dxz.pdf}}}
\hfill
\caption{A compound of two truncated pyramids with a common square base
and opposite orientations.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorCuboctahedron(double length, double height, double height_ratio, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the shared square base, $L$,
\item \texttt{height} of the bottom pyramid, $H$,
\item \texttt{height\_ratio} between the top and the bottom pyramid, $r_H$,
\item \texttt{alpha}, angle between the base and a side face, $\alpha$.
\end{itemize}
They must fulfill
\begin{displaymath}
  H \le \frac{\tan\alpha}{2} L
  \quad\text{and}\quad
  r_h H \le \frac{\tan\alpha}{2} L.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic polyhedron form factor~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V= \dfrac{1}{6} \tan(\alpha)L^3 \Big[ 2
         - \Big(1 - \dfrac{2H }{L\tan(\alpha)} \Big)^3
           - \Big(1 - \dfrac{2 r_H
             H}{L\tan(\alpha) }\Big)^3\Big],
\end{equation*}
\begin{equation*}
  S =L^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Cuboctahedron.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=8$~nm, $H=5$~nm, $r_H=0.5$, and $\alpha=60^\circ$,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Agrees with \E{Cuboctahedron} form factor of \IsGISAXS\
\cite[Eq.~2.34]{Laz06} \cite[Eq.~218]{ReLL09},
except for different parametrization $L=2R_{\rm{\Code{IsGISAXS}}}$.
Since \BornAgain-1.6 implemented
using the generic polyhedron form factor \cite{Wut17}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Box} if $\alpha=0$,
\item \ffref{Pyramid} if $r_H\to\infty$.
\end{itemize}


%===============================================================================
\ffsection{Cylinder} \label{SCylinder}
%===============================================================================
\index{Cylinder}
\index{FormFactorCylinder@\Code{FormFactorCylinder}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Cylinder3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Cylinder2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{-2.5mm}{\includefinal{.3\TW}{fig/cuts/Cylinder2dxz.pdf}}}
\hfill
\caption{An upright circular cylinder.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorCylinder(double radius, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius} of the circular base, $R$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  q_{\parallel} \coloneqq \sqrt{q_x^2+q_y^2}.
\end{equation*}
Note that this does \E{not} involve the sesquilinear product
$|q_x|^2=q_x^* q_x$ but the plain product $q_xq_x$ of complex numbers
(and analogous for~$q_y$).

Results:
\begin{equation*}
  F=  2\pi R^2 H  \sinc\left(q_ z \frac{H}{2}\right) \exp\left(i q_ z \frac{H}{2}\right)
    \frac{J_1(q_{\parallel} R )}{q_{\parallel} R },
\end{equation*}
\begin{equation*}
  V = \pi R^2 H,
\end{equation*}
\begin{equation*}
  S=\pi R^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Cylinder.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=3$~nm and $H=8.8$~nm,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).}
\end{figure}

\paragraph{History and Derivation}\strut\\
For real wavevectors, this form factor is well known;
it goes back to Lord Rayleigh.
In \IsGISAXS, it has been implemented as form factor \E{Cylinder}
\cite[Eq.~2.27]{Laz06} \cite[Eq.~223]{ReLL09},
allowing for complex wavevectors.

Since it is not obvious that the standard formula also holds for complex~$\q$,
let us provide a derivation. We only consider the integral over the polar angle,
\begin{equation}
  I(\q) \coloneqq \int_0^{2\pi}\!\d\varphi\,\exp\left(iq_xr\sin\varphi+iq_yr\cos\varphi\right).
\end{equation}
With the abbreviations $a\coloneqq r(q_x+iq_y)/2$ and $b\coloneqq r(q_x-iq_y)/2$,
\begin{equation}
  I(\q) = \int_0^{2\pi}\!\d\varphi\,\exp\left(a\e^{i\varphi}-b\e^{-i\varphi}\right).
\end{equation}
Expansion of the exponential, combined with a binomial expansion of its argument, yields
\begin{equation}
  I(\q)
  = \int_0^{2\pi}\!\d\varphi\,
  \sum_{n=0}^\infty\sum_{k=0}^n(-)^k\frac{a^{n-k}b^{k}}{(n-k)!k!}\e^{i(n-2k)\varphi}.
\end{equation}
The integral over $\varphi$ vanishes except for $n=2k$. Hence
\begin{equation}
  I(\q)
  = 2\pi \sum_{k=0}^\infty(-)^k\frac{{\sqrt{ab}\,}^{2k}}{k!k!}
  = 2\pi J_0\left(rq_\parallel\right).
\end{equation}
To compute the ensueing radial integral $\int \d r r J_0(rq_\parallel)$,
use $t J_0(t)= \d[t J_1(t)]/\d t$ \cite[Formula~9.1.30a]{AbSt64}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Cone} or \ffref{FullSpheroid} if radius varies with~$z$,
\item \ffref{EllipsoidalCylinder} if cross secion is an ellipse.
\end{itemize}


%===============================================================================
\ffsection{Dodecahedron} \label{SDodecahedron}
%===============================================================================
\index{Dodecahedron}
\index{Platonic solid!dodecahedron}
\index{FormFactorDodecahedron@\Code{FormFactorDodecahedron}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\strut\hfill
%\subfigure[Perspective]
{\includefinal{.24\TW}{fig/blue/Dodecahedron3d.png}}
%\hfill
%\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Box2dxy.pdf}}
%\hfill
%\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Box2dxz.pdf}}}
\hfill\strut
\caption{A regular dodecahedron.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorDodecahedron(double edge)
\end{lstlisting}
with the parameter
\begin{itemize}
\item \texttt{edge}, length of one edge, $a$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic form factor of a polyhedron
             with inversion symmetry~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V= \frac{1}{4} (15+7\sqrt{5}) a^3 \approx 7.663\,a^3,
\end{equation*}
%\begin{equation*}
%  S = %% wait for Holden, Shapes, Space, and Symmetry
%\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Dodecahedron_sym.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $a=3.2$~nm,
for three orientations of high symmetry:
$x$ axis perpendicular to a polygonal face;
vertex on the $x$ axis;
edge in the $xy$ plane and perpendicular to the $x$ axis.}
\end{figure}

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Dodecahedron_asy.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $a=3.2$~nm,
for three orientations of decreasing symmetry:
base pentagon in $xy$ plane and pointing in $x$ direction;
rotated by $13^\circ$ around the $z$ axis;
ditto, and tilted by $9^\circ$ around the $x$ axis.}
\end{figure}

\paragraph{History}\strut\\
New in \BornAgain-1.6,
based on the generic form factor of the polyhedron~\cite{Wut17}.


%===============================================================================
\ffsection{Dot} \label{SDot}
%===============================================================================
\index{Dot}
\index{FormFactorDot@\Code{FormFactorDot}}

\paragraph{Real-space geometry}\strut\\

A point with no spatial extension,
hence with a constant form factor.
This is unphysical,
but can be used e.~g.\ to study structure factors without overlayed form factor oscillations.
To get dimensions right, this form factor nonetheless takes an argument
that specifies the radius of a \ffref{FullSphere} with same forward scattering power.

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorDot(double radius)
\end{lstlisting}
with parameter
\begin{itemize}
\item \texttt{radius}, $R_\text{scat}$, radius of sphere with same~$F(0)$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F = \frac{4\pi}{3} R_\text{scat}^3,
\end{equation*}
\begin{equation*}
  V = 0,
\end{equation*}
\begin{equation*}
  S= 0.
\end{equation*}

\paragraph{History}\strut\\

Up to BornAgain 1.16, we simply had $F=1$.
The parameter $R_\text{scat}$ was introduced in release 1.17 to get
dimensions right and to ensure correct intensity scales.

\paragraph{See also}
\begin{itemize}
\item \ffref{FullSphere},
\item \ffref{GaussianCoil}.
\end{itemize}


%===============================================================================
\ffsection{EllipsoidalCylinder} \label{SEllipsoidalCylinder}
%===============================================================================
\index{Ellipsoidal cylinder}
\index{Cylinder!ellipsoidal}
\index{FormFactorEllipsoidalCylinder@\Code{FormFactorEllipsoidalCylinder}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/EllipsoidalCylinder3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/EllipsoidalCylinder2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{4mm}{\includefinal{.3\TW}{fig/cuts/EllipsoidalCylinder2dxz.pdf}}}
\hfill
\caption{A upright cylinder whose cross section is an ellipse.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorEllipsoidalCylinder(double radius_a, double radius_b, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius\_a}, in $x$ direction, $R_a$,
\item \texttt{radius\_b}, in $y$ direction, $R_b$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  \gamma \coloneqq \sqrt{(q_x R_a)^2+(q_y R_b)^2}
\end{equation*}
Results:
\begin{equation*}
F = 2\pi R_a R_b H \exp\left(i\frac{q_z H}{2}\right)
   \sinc\left(\frac{q_z H}{2}\right) \frac{J_1(\gamma)}{\gamma},
\end{equation*}
\begin{equation*}
  V = \pi R_a R_bH,
\end{equation*}
\begin{equation*}
  S = R_a R_b.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_EllipsoidalCylinder.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R_a=6.3$~nm, $R_b=4.2$~nm and $H=3$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Agrees with the \IsGISAXS\ form factor
\E{Ellipsoid} \cite[Eq.~2.41, wrongly labeled in Fig.~2.4]{Laz06}
or \E{Ellipsoidal Cylinder} \cite[Eq.~224]{ReLL09}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Cylinder} if $R_a=R_b$.
\end{itemize}


%===============================================================================
\ffsection{FullSphere} \label{SFullSphere}
%===============================================================================
\index{Ball|see{Sphere}}
\index{Full sphere}
\index{Sphere}
\index{FormFactorFullSphere@\Code{FormFactorFullSphere}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/FullSphere3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/FullSphere2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{-2mm}{\includefinal{.3\TW}{fig/cuts/FullSphere2dxz.pdf}}}
\hfill
\caption{A full sphere.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorFullSphere(double radius)
\end{lstlisting}
with the parameter
\begin{itemize}
\item \texttt{radius}, $R$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  q \coloneqq \sqrt{q_x^2+q_y^2+q_z^2}.
\end{equation*}
Note that this does \E{not} involve the sesquilinear product
$|q_x|^2=q_x^* q_x$ but the plain product $q_xq_x$ of complex numbers
(and analogous for~$q_y$, $q_z$).
\begin{equation*}
F = \frac{4\pi}{q^3} \exp(iq_z R)\left[\sin(qR) - qR \cos(qR)\right],
\end{equation*}
\begin{equation*}
  V = \dfrac{4\pi}{3}R^3,
\end{equation*}
\begin{equation*}
  S= \pi R^2.
\end{equation*}

\paragraph{Example}\nopagebreak\strut\nopagebreak

\begin{figure}[H]
\begin{center}
\includefinal{.5\TW}{fig/ff2/ff_FullSphere.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=3.9$~nm.}
\end{figure}

\paragraph{History and Derivation}\strut\\
For real wavevectors, this form factor is well known;
it goes back at least to Lord Rayleigh.
In \IsGISAXS, it has been implemented as form factor \E{Full sphere}
\cite[Eq.~2.36]{Laz06} \cite[Eq.~226]{ReLL09},
allowing for complex wavevectors.
Since it is not obvious that Rayleigh's formula also holds for complex~$\q$,
let us outline a derivation
(if you know a more elegant one, we would like to hear).

If the origin is at the center of the sphere, then the form factor is
\begin{equation}
I(\q,R)
 = \int_0^R\d r\, r^2\int_0^{\pi}\d\theta\,\sin\theta\int_0^{2\pi}\d\varphi
  \:\e^{i\q\r}
\end{equation}
with $\q\r
= q_x r\sin\theta\cos\varphi + q_y r\sin\theta\sin\varphi + q_z r\cos\theta$.
For the integration over $\varphi$,
see \cref{SCylinder} on the form factor of a cylinder:
\begin{equation}
  I(\q,R)
  = 2\pi \int_0^R \d r\,r^2 \int_0^{\pi} \d\theta\, \sin\theta
   \exp\left(i q_z \cos \theta\right) J_0\left(q_\parallel r\sin \theta\right)
\end{equation}
with $q_{\parallel}=\sqrt{q_x^2+q_y^2}$.
By symmetry, the imaginary part is zero,
so that the exponential reduces to a cosine:
\begin{equation}
  I(\q,R)
  = 2\pi \int_0^R \d r\,r^2 \int_0^{\pi} \d\theta\, \sin\theta
   \cos\left(q_z \cos \theta\right) J_0\left(q_\parallel r\sin \theta\right).
\end{equation}
Expand the outer cosine and the Bessel function:
\begin{equation}
  I(\q,R)
  = 2\pi \int_0^R \d r\,r^2 \int_0^{\pi} \d\theta\, \sin\theta
    \sum_{j=0}^\infty (-)^j \frac{(q_zr\cos\theta)^{2j}}{(2j)!}\,
    \sum_{k=0}^{\infty} (-)^k \frac{(q_\parallel r \sin\theta)^{2k}}{4^k k!^2}.
\end{equation}
Sort by powers of $r$, and integrate:
\begin{equation}
  I(\q,R)
  = 2\pi \sum_{n=0}^\infty (-)^n \frac{R^{2n+3}}{2n+3} \sum_{k=0}^n
    \frac{{q_z}^{2n-2k}}{(2n-2k)!}\,\frac{{q_\parallel}^{2k}}{4^k k!^2} \zeta(k,n)
\end{equation}
with
\begin{equation}
  \zeta(k,n)
  \coloneqq \int_0^{\pi} \d\theta\, \sin\theta
  (\cos\theta)^{2n-2k}(\sin\theta)^{2k}.
\end{equation}
This integral \cite[no.\ 2.512.4]{GrRy07} yields
\begin{equation}
  \zeta(k,n)
  = \frac{2^{2k+1}(2n-2k)! n! k!}{(2n+1)!(n-k)!}.
\end{equation}
Hence
\begin{equation}\label{ESphereU}
  I(\q,R)
  = 4\pi \sum_{n=0}^\infty (-)^n \frac{R^{2n+3}}{(2n+3)(2n+1)!}
    \sum_{k=0}^n \frac{n!}{(n-k)!k!}{q_z}^{2n-2k}{q_\parallel}^{2k}.
\end{equation}
The inner sum happens to be the binomial expansion of
$q^{2n}=\left({q_z}^2+{q_\parallel}^2\right)^n$.
Therefore \cref{ESphereU} coincides with the series expansion of
\begin{equation}
  I(\q,R)
  = 4\pi q^{-3} \left( \sin(qR) - qR\cos(qR) \right),
\end{equation}
which is what we wanted to prove.

\paragraph{See also}
\begin{itemize}
\item \ffref{Dot} for $R\to0$ (but keeping $V$ finite),
\item \ffref{Cylinder},
\item \ffref{FullSpheroid},
\item \ffref{TruncatedSphere}.
\end{itemize}

%===============================================================================
\ffsection{FullSpheroid} \label{SFullSpheroid}
%===============================================================================
\index{Full spheroid}
\index{Spheroid}
\index{FormFactorFullSpheroid@\Code{FormFactorFullSpheroid}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/FullSpheroid3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/FullSpheroid2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{-3mm}{\includefinal{.3\TW}{fig/cuts/FullSpheroid2dxz.pdf}}}
\hfill
\caption{A full spheroid, generated by rotating an ellipse around the vertical axis.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorFullSpheroid(double radius, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius}, $R$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
 h \coloneqq H/2, \quad
 s \coloneqq \sqrt{(R q_x)^2 + (R q_y)^2 + (h q_z)^2}.
\end{equation*}
Results:
\begin{equation*}
  F = 4\pi \exp(i q_z h) R^2 h\frac{\sin(s)-s\cos(s)}{s^3},
\end{equation*}
\begin{equation*}
  V =\dfrac{4\pi}{3}R^2h,
\end{equation*}
\begin{equation*}
  S =\pi R^2.
\end{equation*}

\paragraph{Example}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_FullSpheroid.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=3.5$~nm and $H=9.8$~nm,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).}
\end{figure}

\paragraph{History and Derivation}\strut\\
Replicates the \E{Full spheroid} of \IsGISAXS\
\cite[Eq.~2.37]{Laz06} \cite[Eq.~227]{ReLL09},
except for wrong factors of~2 in their volume formula and form factor implementation.
Up to BornAgain 1.16,
our form factor computation followed \IsGISAXS\
in using numeric integration in the~$z$ coordinate.

Thanks to Matt Thompson (Australian National University)
who pointed out that
the form factor of any spheroid
can be reduced to that of the regular sphere (\cref{SFullSphere})
by rescaling $\r\q=(M\r)(M^{-1}\q)$.
In the present case (with revolution axis along~$z$),
the transformation matrix is just $M=\text{diag}(1/R, 1/R, 1/h)$.
The resulting simple expression for the form factor
goes back at least to Guinier \cite[p.~193]{Gui39}.

\paragraph{See also}
\begin{itemize}
\item \ffref{FullSphere} if $H=2R$,
\item \ffref{TruncatedSpheroid} if cut horizontally.
\end{itemize}

%===============================================================================
\ffsection{HemiEllipsoid} \label{SHemiEllipsoid}
%===============================================================================
\index{Hemi ellipsoid}
\index{Ellipsoid!truncated}
\index{Truncation!ellipsoid}
\index{FormFactorHemiEllipsoid@\Code{FormFactorHemiEllipsoid}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/HemiEllipsoid3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/HemiEllipsoid2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{5mm}{\includefinal{.3\TW}{fig/cuts/HemiEllipsoid2dxz.pdf}}}
\hfill
\caption{An horizontally oriented ellipsoid, truncated at the central plane.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorHemiEllipsoid(double radius_a, double radius_b, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius\_a}, in $x$ direction, $R_a$,
\item \texttt{radius\_b}, in $y$ direction, $R_b$,
\item \texttt{height}, equal to radius in $z$ direction, $H$
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
 r_{a,z} \coloneqq R_a \sqrt{1-\left(\dfrac{z}{H} \right)^2},\quad
 r_{b,z} \coloneqq R_b \sqrt{1-\left(\dfrac{z}{H} \right)^2}, \quad
 \gamma_z =\sqrt{(q_x r_{a,z})^2+(q_y r_{b,z})^2}.
\end{equation*}
Results:
\begin{equation*}
  F = 2\pi \int_0^{H} \!\d z\, r_{a,z} r_{b,z}
                               \frac{J_1(\gamma_z)}{\gamma_z}\exp(iq_z z),
\end{equation*}
\begin{equation*}
  V = \dfrac{2}{3}\pi R_a R_bH,
\end{equation*}
\begin{equation*}
  S =\pi R_a R_b.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_HemiEllipsoid.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R_a=10$~nm, $R_b=3.8$~nm and $H=3.2$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Agrees with the \IsGISAXS\ form factor
\E{Anisotropic hemi-ellipsoid}
\cite[Eq.~2.42, with wrong sign in the $z$-dependent phase factor]{Laz06}
or \E{Hemi-spheroid} \cite[Eq.~229]{ReLL09}.

\paragraph{See also}
\begin{itemize}
\item \ffref{TruncatedSpheroid} if $R_a=R_b$,
\item \ffref{TruncatedSphere} if $R_a=R_b=H$.
\end{itemize}


%===============================================================================
\ffsection{Icosahedron} \label{SIcosahedron}
%===============================================================================
\index{Icosahedron}
\index{Platonic solid!icosahedron}
\index{FormFactorIcosahedron@\Code{FormFactorIcosahedron}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\strut\hfill
%\subfigure[Perspective]
{\includefinal{.24\TW}{fig/blue/Icosahedron3d.png}}
%\hfill
%\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Box2dxy.pdf}}
%\hfill
%\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Box2dxz.pdf}}}
\hfill\strut
\caption{A regular icosahedron.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorIcosahedron(double edge)
\end{lstlisting}
with the parameter
\begin{itemize}
\item \texttt{edge}, length of one edge, $a$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic form factor of a polyhedron
             with inversion symmetry~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V= \frac{5}{12} (3+\sqrt5)a^3 \approx 2.182\,a^3
\end{equation*}
%\begin{equation*}
%  S = %% wait for Holden, Shapes, Space, and Symmetry
%\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Icosahedron_sym.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $a=4.8$~nm,
for three orientations of high symmetry:
$x$ axis perpendicular to a polygonal face;
vertex on the $x$ axis;
edge in the $xy$ plane and perpendicular to the $x$ axis.}
\end{figure}

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Icosahedron_asy.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $a=4.8$~nm,
for three orientations of decreasing symmetry:
base pentagon in $xy$ plane and pointing in $x$ direction;
rotated by $13^\circ$ around the $z$ axis;
ditto, and tilted by $9^\circ$ around the $x$ axis.}
\end{figure}

\paragraph{History}\strut\\
New in \BornAgain-1.6,
based on the generic form factor of the polyhedron~\cite{Wut17}.


%===============================================================================
\ffsection{Prism3 (triangular)} \label{SPrism3}
%===============================================================================
\index{Prism!triangular}
\index{FormFactorPrism3@\Code{FormFactorPrism3}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Prism33d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Prism32dxy.ps}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Prism32dxz.ps}}
\hfill
\caption{A prism based on an equilateral triangle.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorPrism3(double length, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of one base edge, $L$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
F = H \sinc\left(q_z\frac{H}{2}\right) \exp\left(-i q_z\frac{ H}{2}\right) F_\parallel(\q_\parallel)
\end{equation*}
with the form factor $F_\parallel$ of the base triangle
computed using the generic form factor of a planar polygon \cite{Wut17},
\begin{equation*}
  V= \dfrac{\sqrt{3}}{4} H L^2,
\end{equation*}
\begin{equation*}
  S =\dfrac{\sqrt{3}}{4}L^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Prism3.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=13.8$~nm and $H=3$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\label{fig:FFprism3Ex}
\end{figure}

\paragraph{History}\strut\\
Has been validated against the \E{Prism3} form factor of \IsGISAXS\
\cite[Eq.~2.29]{Laz06} \cite[Eq.~219]{ReLL09}.
Note the different parameterization $L= 2 R_{\rm{\Code{IsGISAXS}}}$.
In \FitGISAXS\ just called \E{Prism} \cite{Bab13}.
In \BornAgain-1.6,
redefined to let the $x$ axis point along a symmetry axis
(rotated by $30^\circ$ with respect to the previous version).

Reimplemented in \BornAgain-1.6 using the generic form factor
of a polygonal prism \cite{Wut17},
to achieve numerical stability near the removable singularity at $q\to0$.

\paragraph{See also}
\begin{itemize}
\item \ffref{Tetrahedron} (trigonal pyramid) if sides are not vertical.
\end{itemize}


%===============================================================================
\ffsection{Prism6 (hexagonal)} \label{SPrism6}
%===============================================================================
\index{Prism!hexagonal}
\index{FormFactorPrism6@\Code{FormFactorPrism6}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Prism63d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Prism62dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{-3mm}{\includefinal{.3\TW}{fig/cuts/Prism62dxz.pdf}}}
\hfill
\caption{A prism based on a regular hexagon.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorPrism6(double radius, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius} of the hexagonal base, $R$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
F = H \sinc\left(q_z\frac{H}{2}\right) \exp\left(-i q_z\frac{ H}{2}\right) F_\parallel(\q_\parallel)
\end{equation*}
with the form factor $F_\parallel$ of the base hexagon
computed using the generic form factor of a planar polygon
with two-fold symmetry~($S_2$) \cite{Wut17},
\begin{equation*}
  V = \dfrac{3\sqrt{3}}{2}H R^2,
\end{equation*}
\begin{equation*}
  S =\dfrac{3\sqrt{3}R^2}{2}.
\end{equation*}

\paragraph{Examples}\strut\nopagebreak

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Prism6.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=5.7$~nm and $H=3$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\label{fig:FFprism6Ex}
\end{figure}

\paragraph{History}\strut\\
Has been validated against the \E{Prism6} form factor of \IsGISAXS\
\cite[Eq.~2.31]{Laz06} \cite[Eq.~221]{ReLL09},
which has different parametrization
and lacks a factor $H$ in $F(\q)$.

Reimplemented in \BornAgain-1.5 using the generic form factor
of a polygonal prism with symmetry~$S_2$ \cite{Wut17},
to achieve numerical stability near the removable singularity at $q\to0$.

\paragraph{See also}
\begin{itemize}
\item \ffref{Cone6} (frustum with hexagonal base) if sides are not vertical.
\end{itemize}


%===============================================================================
\ffsection{Pyramid (square-based)}\label{SPyramid}
%===============================================================================
\index{Pyramid!square}
\index{Frustum!square base}
\index{FormFactorPyramid@\Code{FormFactorPyramid}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Pyramid3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Pyramid2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Pyramid2dxz.pdf}}}
\hfill
\caption{A truncated pyramid with a square base.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorPyramid(double length, double height, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of one edge of the square base, $L$,
\item \texttt{height}, $H$,
\item \texttt{alpha}, angle between the base and a side face, $\alpha$,
\end{itemize}
They must fulfill
\begin{displaymath}
  H \le \frac{\tan\alpha}{2}L.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic polyhedron form factor~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V = \dfrac{1}{6}  L^3 \tan\alpha\left[ 1
             - \left(1 - \dfrac{2H}{L\tan\alpha}\right)^3 \right],,
\end{equation*}
\begin{equation*}
  S = L^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Pyramid.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=10$~nm, $H=4.2$~nm and $\alpha=60^{\circ}$,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Corresponds to \E{Pyramid} form factor of \IsGISAXS\
\cite[Eq.~2.31]{Laz06} \cite[Eq.~221]{ReLL09},
except for different parametrization $L=2R_{\rm{\Code{IsGISXAXS}}}$
and a corrected sign.

Reimplemented in \BornAgain-1.6 using the generic form factor
of a polygonal prism \cite{Wut17},
to achieve numerical stability near the removable singularity at $q\to0$.

\paragraph{See also}
\begin{itemize}
\item \ffref{AnisoPyramid} if base is rectangular,
\item \ffref{Box} if $\alpha=0$.
\end{itemize}


%===============================================================================
\ffsection{Tetrahedron} \label{STetrahedron}
%===============================================================================
\index{Tetrahedron}
\index{Frustum!triangular base}
\index{Pyramid!rectangular}
\index{Platonic solid!tetrahedron}
\index{FormFactorTetrahedron@\Code{FormFactorTetrahedron}}

\paragraph{Real-space geometry}\strut\\

\noindent
Incorrectly named so, since it actually has five, not four surfaces.
It's a frustum with trigonal base.

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Tetrahedron3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Tetrahedron2dxy.ps}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Tetrahedron2dxz.ps}}
\hfill
\caption{A truncated pyramid, based on an equilateral triangle.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorTetrahedron(double length, double height, double alpha)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of one edge of the equilateral triangular base, $L$,
\item \texttt{height}, $H$,
\item \texttt{alpha}, dihedral angle between the base and a side face, $\alpha$.
\end{itemize}
They must fulfill
\begin{displaymath}
  H\le \frac{\tan{\alpha}}{2\sqrt{3}} L.
\end{displaymath}
The orthographic projection also shows the angle~$\beta$ between the base and a side edge.
It is related to the dihedral angle through $\tan \alpha = 2 \tan \beta$.

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F\text{~: computed using the generic polyhedron form factor~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V= \dfrac{\tan(\alpha) L^3}{24} \left[1- \left(1 -
  \dfrac{2\sqrt{3} H}{L \tan(\alpha)} \right)^3\right],
\end{equation*}
\begin{equation*}
  S =\dfrac{\sqrt{3}}{4}L^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Tetrahedron.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=12$~nm, $H=8$~nm, and $\alpha=75^\circ$,
for four different angles~$\omega$ of rotation around the $z$ axis.
The low symmetry requires other angular ranges than used in most other figures.}
\end{figure}

\paragraph{History}\strut\\
Previous implementations as \E{Tetrahedron} in \IsGISAXS\
\cite[Eq.~2.30]{Laz06} \cite[Eq.~220]{ReLL09},
and as  \E{Truncated tetrahedron} in \FitGISAXS\ \cite{Bab13}.
In \BornAgain-1.6,
redefined to let the $x$ axis lie in a mirror plane
(rotated by $30^\circ$ with respect to the previous version).

Up to \BornAgain-1.5, we computed the form factor by numeric integration, as in \IsGISAXS.
Since \BornAgain-1.6 higher speed and accuracy are achieved
by using the generic polyhedron form factor \cite{Wut17},
with series expansions near singularities.

\paragraph{See also}
\begin{itemize}
\item \ffref{Prism3} if $\alpha=0$.
\end{itemize}


%===============================================================================
\ffsection{TruncatedCube} \label{STruncatedCube}
%===============================================================================
\index{Cube!truncated}
\index{Truncation!cube}
\index{FormFactorTruncatedCube@\Code{FormFactorTruncatedCube}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/TruncatedCube.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Facettedcube1_2dxy.pdf}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Facettedcube1_2dxz.pdf}}
\hfill
\caption{A cube whose eight vertices have been removed.
The truncated part of each vertex is a trirectangular tetrahedron.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorTruncatedCube(double length, double removed_length)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the full cube, $L$,
\item \texttt{removed\_length}, side length of the trirectangular tetrahedron removed from the cube's vertices, $t$.
\end{itemize}
They must fulfill
\begin{displaymath}
  t \le L/2.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F \text{~: computed using the generic form factor of a polyhedron
             with inversion symmetry~\cite{Wut17},}
\end{equation*}
\begin{equation*}
  V = L^3 - \dfrac{4}{3}t^3,
\end{equation*}
\begin{equation*}
  S = L^2.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_TruncatedCube.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=25$~nm, $W=10$~nm, $H=8$~nm, and $d=5$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Until BornAgain--1.17 named \texttt{TruncatedCube}.
Reimplemented in BornAgain--1.6 using the generic form factor
of a polygonal prism \cite{Wut17}.
Motivated by \cite{HeSS74}.

\paragraph{See also}
\begin{itemize}
\item \ffref{Box} if $t=0$,
\item \ffref{CantellatedCube} if edges are also facetted.
\end{itemize}


%===============================================================================
\ffsection{TruncatedSphere}\label{STruncatedSphere}
%===============================================================================
\index{Sphere!segment}
\index{Truncation!sphere}
\index{FormFactorTruncatedSphere@\Code{FormFactorTruncatedSphere}}
\index{Segment!spherical}

A \E{spherical segment}, obtained from a spherical ball by two parallel cuts.

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Sphere3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Sphere2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{-2mm}{\includefinal{.3\TW}{fig/cuts/Sphere2dxz.pdf}}}
\hfill
\caption{A truncated sphere.}
\end{figure}
\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorTruncatedSphere(double radius, double height, double dh)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius}, $R$,
\item \texttt{height}, $H$,
\item \texttt{top removal}, $dh$.
\end{itemize}
They must fulfill
\begin{equation*}
   0 < H\leq 2R,
\end{equation*}
\begin{equation*}
  dh < H.
\end{equation*}

\paragraph{Special cases}\strut\\
\index{Cap}%
\index{Sphere!cap}%
A \E{spherical cap} is obtained from a spherical ball by a single cut.
This is covered by the following special parameterization of \texttt{TruncatedSphere}:
\begin{itemize}
\item Single cut at the bottom: $dh=0$.
\item Single cut at the top: $H=2R$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  q_{\parallel} \coloneqq \sqrt{q_x^2+q_y^2},\quad
  R_z \coloneqq \sqrt{R^2-z^2}.
\end{equation*}
Results:
\begin{equation*}
F= 2\pi \exp[i q_z (H-R)]\int_{R-H}^{R-dh}\!\d z\, R_z^2
       \frac{J_1(q_{\parallel} R_z) }{q_{\parallel} R_z} \exp(i q_z z) dz,
\end{equation*}
\begin{equation*}
  V=\frac{\pi}{3} \left[ 3R\left(H^2-dh^2\right) +dh^3 - H^3 \right],
\end{equation*}
\begin{equation*}
  S = \left\{\begin{array}{ll} \pi\left(2RH-H^2\right), & H < R \\
                               \pi R^2, & H \geq R,\; dh < R \\
                               \pi\left(2Rdh-dh^2\right), & H \geq R,\; dh \geq R
                                 \end{array}\right..
\end{equation*}

\paragraph{Example}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_TruncatedSphere.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=4.2$~nm and $H=6.1$~nm,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).}
\end{figure}

\paragraph{History and Derivation}\strut\\
Agrees with the \IsGISAXS\ form factor
\E{Sphere} \cite[Eq.~2.33]{Laz06} or
\E{Truncated sphere} \cite[Eq.~228]{ReLL09}.
Justification for complex~$q$ in the same way as for the \E{Cylinder} form factor
in \cref{SCylinder}.

\paragraph{See also}
\begin{itemize}
\item \ffref{FullSphere} if $dh=0$ and $H=2R$,
\item \ffref{TruncatedSpheroid} if vertically stretched or squeezed.
\end{itemize}



%===============================================================================
\ffsection{TruncatedSpheroid} \label{STruncatedSpheroid}
%===============================================================================
\index{Spheroid!truncated}
\index{Truncation!spheroid}
\index{FormFactorTruncatedSpheroid@\Code{FormFactorTruncatedSpheroid}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Spheroid3d.png}}
\hfill
\subfigure[Top view]{\raisebox{5mm}{\includefinal{.3\TW}{fig/cuts/Spheroid2dxy.pdf}}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Spheroid2dxz.pdf}}
\hfill
\caption{A vertically oriented, horizontally truncated spheroid.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorTruncatedSpheroid(double radius, double height, double height_flattening, double dh)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{radius}, $R$,
\item \texttt{height}, $H$,
\item \texttt{height\_flattening}, $f_p$,
\item \texttt{top removal}, $dh$.
\end{itemize}
They must fulfill
\begin{equation*}
  0< \dfrac{H}{R}\le 2f_p.
\end{equation*}
\begin{equation*}
  dh < H.
\end{equation*}

\paragraph{Form factor, volume, horizontal section}\strut\\
Notation:
\begin{equation*}
  q_{\parallel} \coloneqq \sqrt{q_x^2+q_y^2}, \quad
  R_z \coloneqq \sqrt{R^2-z^2/f_p^2}.
\end{equation*}
Results:
\begin{equation*}
F =   2\pi \exp[iq_z(H-f_pR)] \int_{f_p R-H}^{f_p R-dh} \!\d z\,
     R_z^2\frac{J_1(q_{\parallel}R_z)}{q_{\parallel}R_z} \exp(i q_z z)
\end{equation*}
\begin{equation*}
  V=\frac{\pi}{3f_p^2} \left[ 3R f_p\left(H^2-dh^2\right) +dh^3 - H^3 \right],
\end{equation*}
\begin{equation*}
  S = \left\{\begin{array}{ll} \pi\left(2Rf_pH-H^2\right)/f_p^2, & H < Rf_p \\
                               \pi R^2, & H \geq Rf_p,\; dh < Rf_p \\
                               \pi\left(2Rf_pdh-dh^2\right)/f_p^2, & H \geq Rf_p,\; dh \geq Rf_p
                                 \end{array}\right..
\end{equation*}

\paragraph{Example}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_TruncatedSpheroid.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $R=3.3$~nm, $H=9.8$~nm, and $f_p=1.8$,
for four different tilt angles~$\vartheta$ (rotation around the $y$ axis).}
\end{figure}

\paragraph{History and Derivation}\strut\\
Agrees with the \IsGISAXS\ form factor
\E{Sphere} \cite[Eq.~2.33]{Laz06} or
\E{TruncatedSpheroid} \cite[Eq.~228]{ReLL09}.
% Note an erroneous factor~2 in the expression of the volume
% in the \Code{IsGISAXS} manual.
Justification for complex~$q$ in the same way as for the \E{Cylinder} form factor
in \cref{SCylinder}.

\paragraph{See also}
\begin{itemize}
\item \ffref{FullSpheroid} if $dh=0$ and $H=2f_p R$,
\item \ffref{TruncatedSphere} if $f_p=1$.
\end{itemize}


\index{Particle!hard|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Ripples}\label{SRipple}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{Ripple|(}
\index{Particle!elongated|see{Ripple}}

Elongated particles, or ripples, are typically used to model lamellar cuts or man-made gratings.

As everywhere else in BornAgain
only single scattering in the DWBA is simulated.
This can be insufficient for periodic gratings
that cause noticeable higher-order diffraction.
To account for such dynamic scattering effects,
it may be advisable to compute Bloch waves \cite{AsSW10}
or use finite elements to solve the exact wave equation \cite{SoFP17}.
For the foreseeable future, this is not in the scope of BornAgain.

We choose ripples to be elongated in $x$ direction.
Different profiles in the $yz$ plane can be chosen:
box, sinusoidal [\ffref{Ripple1}], saw-tooth [\ffref{Ripple2}].

For each of them, different profiles can also be chosen in the $xz$ plane,
each of them characterized by a single parameter \texttt{length},~$L$.
Their transverse form factor,
\index{Transverse form factor}%
along the elongation axis~$x$, is
\begin{equation}\label{EFparallel}
    f_\parallel(q_x) = \left\{\begin{array}{l@{\quad}l}
    L\sinc(q_x L/2) &\texttt{box,}\\
    L\exp(-(q_x L)^2/8) &\texttt{Gauss,}\\
    L/(1+(q_x L)^2) &\texttt{Lorentz.}
    \end{array}\right.
\end{equation}
Constant factors have been chosen so that the forward scattering is the same
in all three cases, $f_\parallel(0)=L$.
The form factor is the Fourier transform of a correlation function.
The \texttt{box} form factor with its characteristic sinc function
is the Fourier transform of a rectangle function.
A typical application could be a sample with tiny lateral extension
that is fully illuminated by a coherent incoming plane wave.
In most other situations, the correlation function is smooth rather than rectangular.
The \texttt{length} parameter then stands for a correlation length.
\index{Correlation length}%
It is dominated either by a finite extension of the ripple,
or by the coherence length
\index{Coherence length}%
of the scattering setup.
The \texttt{Gauss} form factor is the Fourier transform of
a Gaussian
\index{Gaussian!transverse form factor}
correlation function;
the \texttt{Lorentz}
\index{Lorentzian!transverse form factor}
 form factor is the Fourier transform of an exponential in~$|x|$.

\paragraph{History}\strut\\
The \texttt{Box} variant of \E{Ripple1} and \E{Ripple2} replicates
two form factors from \FitGISAXS\ \cite{Bab13}.

Full documentation and API support for all ripple form factors appeared in BornAgain-1.17.
Before that release, the \texttt{Lorentz} factor~$f_\parallel$
had an extra factor of 2.5 in the form factor.


%===============================================================================
\ffsection{Bar (elongated box)} \label{SBar}
%===============================================================================
\index{Box}
\index{FormFactorBox@\Code{FormFactorBox}}
\index{FormFactorBarGauss@\Code{FormFactorBarGauss}}
\index{FormFactorBarLorentz@\Code{FormFactorBarLorentz}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Box3d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Box2dxy.pdf}}
\hfill
\subfigure[Side view]{\raisebox{2mm}{\includefinal{.3\TW}{fig/cuts/Box2dxz.pdf}}}
\hfill
\caption{A bar.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorBox(
     double length, double width, double height)
  FormFactorBarGauss(
     double length, double width, double height)
  FormFactorBarLorentz(
     double length, double width, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length} of the base, $L$,
\item \texttt{width} of the base, $W$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}

\begin{equation*}
F= f_\parallel(q_x) W H\exp\left(i q_z \frac{H}{2}\right)
\sinc\left(q_y \frac{W}{2}\right) \sinc\left(q_z \frac{H}{2}\right)
\end{equation*}
with $f_\parallel$ as defined in~\cref{EFparallel},
\begin{equation*}
  V= LWH,
\end{equation*}
\begin{equation*}
  S = LW.
\end{equation*}

%===============================================================================
\ffsection{Ripple1 (sinusoidal)} \label{SRipple1}
%===============================================================================
\index{Ripple!sinusoidal}
\index{Sinusoidal ripple}
\index{FormFactorRipple1Box@\Code{FormFactorRipple1Box}}
\index{FormFactorRipple1Gauss@\Code{FormFactorRipple1Gauss}}
\index{FormFactorRipple1Lorentz@\Code{FormFactorRipple1Lorentz}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Ripple13d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Ripple12dxy.pdf}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Ripple12dyz.pdf}}
\hfill
\caption{A ripple with a sinusoidal profile.}
\end{figure}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorRipple1Box(
     double length, double width, double height)
  FormFactorRipple1Gauss(
     double length, double width, double height)
  FormFactorRipple1Lorentz(
     double length, double width, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length}, $L$,
\item \texttt{width}, $W$,
\item \texttt{height}, $H$.
\end{itemize}
The ripple is modelled as a surface
\begin{equation*}
  Z(y) = \frac{H}{2}\left[ 1 + \cos\frac{2\pi y}{W} \right].
\end{equation*}

\paragraph{Form factor}\strut\\
Using the inverse profile
\begin{equation*}
  Y(z) = \frac{W}{2\pi}\text{arccos}\left( \frac{2z}{H}-1 \right),
\end{equation*}
the form factor is computed by numeric integration:
\begin{equation*}
F = f_\parallel(q_x)
   \int_0^H\!\d z\,\e^{iq_zz}\, 2Y(z)\sinc\left(q_y Y(z)\right)
\end{equation*}
with $f_\parallel$ defined in~\cref{EFparallel}.
The integration is substantially accelerated by the substitution
$u=\text{arccos}( 2z/H-1)$.

\paragraph{Volume, horizontal section}\strut\\
\begin{equation*}
  V = \dfrac{L W H}{2},
\end{equation*}
\begin{equation*}
  S = L W.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Ripple1.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=25$~nm, $W=10$~nm and $H=8$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.}
\end{figure}

\paragraph{History}\strut\\
Agrees with the \E{Ripple1} form factor of \FitGISAXS\ \cite{Bab13}.

%===============================================================================
\ffsection{Ripple2 (saw-tooth)} \label{SRipple2}
%===============================================================================
\index{Ripple!saw-tooth}
\index{Saw-tooth ripple}
\index{FormFactorRipple2@\Code{FormFactorRipple2Box}}
\index{FormFactorRipple2Gauss@\Code{FormFactorRipple2Gauss}}
\index{FormFactorRipple2Lorentz@\Code{FormFactorRipple2Lorentz}}

\paragraph{Real-space geometry}\strut\\

\begin{figure}[H]
\hfill
\subfigure[Perspective]{\includefinal{.24\TW}{fig/blue/Ripple23d.png}}
\hfill
\subfigure[Top view]{\includefinal{.3\TW}{fig/cuts/Ripple22dxy.pdf}}
\hfill
\subfigure[Side view]{\includefinal{.3\TW}{fig/cuts/Ripple22dyz.pdf}}
\hfill
\caption{A ripple with an asymmetric saw-tooth profile.}
\end{figure}

\FloatBarrier

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorRipple2Box(
     double length, double width, double height, asymmetry)
  FormFactorRipple2Gauss(
     double length, double width, double height, asymmetry)
  FormFactorRipple2Lorentz(
     double length, double width, double height, asymmetry)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{length}, $L$,
\item \texttt{width}, $W$,
\item \texttt{height}, $H$.
\item \texttt{asymmetry}, $d$.
\end{itemize}
They must fulfill
\begin{displaymath}
  |d| \le W/2.
\end{displaymath}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F = f_\parallel(q_x)
  i\e^{-i q_y d}
  \left[
    \e^{i \alpha_{-}/2} \sinc\left( \frac{\alpha_{+}}{2} \right)
    - \e^{i \alpha_{+}/2} \sinc\left( \frac{\alpha_{-}}{2} \right)
  \right],
\end{equation*}
with $f_\parallel$ defined in~\cref{EFparallel}.
\begin{equation*}
  \alpha_{+} = H q_z + \frac{q_y W}{2} + q_y d, \quad
  \alpha_{-} = H q_z - \frac{q_y W}{2} + q_y d,
\end{equation*}
\begin{equation*}
  V = \dfrac{L W H}{2},
\end{equation*}
\begin{equation*}
  S = L W.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Ripple2.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=25$~nm, $W=10$~nm, $H=8$~nm, and $d=5$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.
The low symmetry requires other angular ranges than used in most other figures.}
\end{figure}

\paragraph{History}\strut\\
Agrees with the \E{Ripple2} form factor of \FitGISAXS\ \cite{Bab13}.

\index{Ripple|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\iffalse
\chapter{Soft particles}\label{SSoft}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{Particle!soft|(}

A soft particle is characterized by a relative density~$\rho(\r)$
\index{r@$\rho$ (density)}%
\index{Density}%
that varies smoothly from $\rho(0)=1$ to $\rho(\infty)=0$.
The actual scattering length density~$\rho_\text{s}(\r)$
\index{Scattering length density}%
is the product of a constant bulk value~$\rho_\text{s}$ with~$\rho(\r)$.

The form factor of a soft particle is defined as the Fourier transform of~$\rho(\r)$,
\index{Fourier transform}%
\begin{equation}
  F(\q) = \int\!\d^3r\,\e^{i\q\r}\rho(\r).
\end{equation}
The forward scattering power of the soft particle is the same
as that of a hard particle with volume
\begin{equation}
  V = F(0) = \int\!\d^3r\,\rho(\r).
\end{equation}

%===============================================================================
\ffsection{Gaussian ellispoid} \label{SGauss}
%===============================================================================
\index{Ellipsoid!Gaussian}
\index{Gaussian!soft particle}
\index{FormFactorGauss@\Code{FormFactorGauss}}

\paragraph{Syntax and parameters}\strut\\[-2ex plus .2ex minus .2ex]
\begin{lstlisting}
  FormFactorGauss(double width, double height)
\end{lstlisting}
with the parameters
\begin{itemize}
\item \texttt{width}, $W$,
\item \texttt{height}, $H$.
\end{itemize}

\paragraph{Form factor, volume, horizontal section}\strut\\
\begin{equation*}
  F = \frac{L H}{q_y}
  \sinc\left(\frac{q_xL}{2}\right)
  i\e^{-i q_y d}
  \left[
    \e^{i \alpha_{-}/2} \sinc\left( \frac{\alpha_{+}}{2} \right)
    - \e^{i \alpha_{+}/2} \sinc\left( \frac{\alpha_{-}}{2} \right)
  \right],
\end{equation*}
\begin{equation*}
  \alpha_{+} = H q_z + \frac{q_y W}{2} + q_y d, \quad
  \alpha_{-} = H q_z - \frac{q_y W}{2} + q_y d,
\end{equation*}
\begin{equation*}
  V = \dfrac{L W H}{2},
\end{equation*}
\begin{equation*}
  S = L W.
\end{equation*}

\paragraph{Examples}\strut

\begin{figure}[H]
\begin{center}
\includefinal{1\TW}{fig/ff2/ff_Ripple2.pdf}
\end{center}
\caption{Normalized intensity $|F|^2/V^2$,
computed with $L=25$~nm, $W=10$~nm, $H=8$~nm, and $d=5$~nm,
for four different angles~$\omega$ of rotation around the $z$ axis.
The low symmetry requires other angular ranges than used in most other figures.}
\end{figure}


\index{Particle!soft|)}
\fi
